Copyright: Copyright'94 Instant Replay or its Suppliers


Contents
Visual FX DLL Contents

Introduction

Note: The DLLs are not shipped with this demonstration program. This help file is included for your reference only.

How to add special effects to your programs

Function Syntax

Effects

Distributing the DLL's

Sample Program


Introduction

Visual FX has several parts to it. The first is a DLL called "VISBBFX.DLL". This is a DLL that contains all of the special visual effects. It works by changing calls to the BitBlt function with calls to the BitBltFX function. It has the same parameters and functionality but with additional parameters to specify the effects. The second part is a DLL called "VISLB1FX.DLL". This DLL contains higher level routines ShowDIBFX and ShowWMFFX to directly load from disk and display DIB's, BMP's, and WMF files using special effects. This makes it very easy to add ways of displaying images to programs with only one function call. The third part is the Visual FX sample programs. These C and Pascal programs come complete with source code and everything you need to compile and test using the Visual FX DLL's.


How to add special effects to your program

The Visual Effects are added by making calls to the functions in the DLL's. You should add to the definition file in the IMPORTS section the functions you want to use:

IMPORTS

BitBltFX = VISBBFX.2

BitBltFXStatus = VISBBFX.3

BitBltFXInfo = VISBBFX.4

ShowWMFFX = VISLB1FX.2

ShowDIBFX = VISLB1FX.3

MakeUnivPal256 = VISLB1FX.4

Or you can add the libraries "VISBBFX.LIB" and "VISLB1FX.LIB" to the linker input.

The function prototypes are contained in the header files "VISBBFX.H" and "VISLB1FX.H". You should include these header files into your program:

#include "visbbfx.h"

#include "vislb1fx.h"

If you are using Borland Pascal, there are two Unit source code files (VISBBFX.PAS and VISLB1FX.PAS) that you should put in your USES statement. These files contain the TYPES, CONSTANTS and INTERFACE information for using the Visual FX DLLs. There is a sample Pascal program (VFXPAS.PAS) that shows you how to use these units.

See Also

Function Syntax


Function Syntax

Available functions in Visual FX:

BitBltFX

BitBltFXStatus

BitBltFXInfo

ShowWMFFX

ShowDIBFX

MakeUnivPal256

See Also

How to add special effects to your program


Effects

This is a listing of the constants and descriptions used for the FX parameter to the BitBltFX function. All effects range from BBFX_NORMAL to BBFX_MAX_EFFECT.

Parameter	Value	Description

BBFX_NORMAL	0	Normal Display

BBFX_TTOB	1	Top to bottom

BBFX_BTOT	2	Bottom to Top

BBFX_LTOR	3	Left to Right

BBFX_RTOL	4	Right to Left

BBFX_CLOSE	5	Close

BBFX_OPEN	6	Open

BBFX_CCLOSE	7	Curtain Close

BBFX_COPEN	8	Curtain Open

BBFX_HBLINDS	9	Horizontal Blinds

BBFX_VBLINDS	10	Vertical Blinds

BBFX_EXPLODE	11	Explode

BBFX_TTOB_SLIDE	12	Slide from Top to Bottom

BBFX_BTOT_SLIDE	13	Slide from Bottom to Top

BBFX_LTOR_SLIDE	14	Slide from Left to Right

BBFX_RTOL_SLIDE	15	Slide from Right To Left

BBFX_TTOB_BLOCKS	16	Blocks from Top To Bottom

BBFX_BTOT_BLOCKS	17	Blocks from Bottom To Top

BBFX_LTOR_BLOCKS	18	Blocks from Left To Right

BBFX_RTOL_BLOCKS	19	Blocks from Right To Left

BBFX_TTOB_PUSH	20	Slide from Top To Bottom and Push Screen Contents

BBFX_BTOT_PUSH	21	Slide from Bottom to Top and Push Screen Contents

BBFX_LTOR_PUSH	22	Slide from Left to Right and Push Screen Contents

BBFX_RTOL_PUSH	23	Slide from Right to Left and Push Screen Contents

BBFX_TTOB_STACK	24	Sliding Blocks stacking from Top to Bottom

BBFX_BTOT_STACK	25	Sliding Blocks stacking from Bottom to Top

BBFX_LTOR_STACK	26	Sliding Blocks stacking from Left to Right

BBFX_RTOL_STACK	27	Sliding Blocks stacking from Right to Left

BBFX_SDIAMONDS	28	Small diamonds

BBFX_SHLINES	29	Small horizontal lines

BBFX_STRI	30	Small triangles

BBFX_SHATCH	31	Small hatch

BBFX_SX	32	Small X

BBFX_SSMILES	33	Small smiles

BBFX_CIRCLES_RANDOM	34	Random circles

BBFX_POLY_RANDOM	35	Random polygons

BBFX_RECT_RANDOM	36	Random rectangles

BBFX_CIRCLES_PAT	37	Pattern circles

BBFX_DIAMONDS_PAT	38	Pattern diamonds

BBFX_PIXELFADE	39	Pixel Fade

BBFX_TTOB_WAVE	40	Wave from Top to Bottom

BBFX_BTOT_WAVE	41	Wave from Bottom to Top

BBFX_LTOR_WAVE	42	Wave from Left to Right

BBFX_RTOL_WAVE	43	Wave from Right to Left

BBFX_CLOCK	44	Clock

BBFX_SPIRAL	45	Spiral out

BBFX_PUZZLE	46	Puzzle

BBFX_CIRCUITBOARD	47	Circuit Board

BBFX_UD_SKIPS	48	Skips lines up/down

BBFX_RL_SKIPS	49	Skips lines right/left

BBFX_MOSAIC	50	Mosaic

BBFX_MOSAIC_CAN	51	Mosaic using canvas

BBFX_IMPLODE_MOSAIC	52	Implode Mosaic

BBFX_IMPLODE_MOSAIC_CAN	53	Implode Mosaic using canvas

BBFX_TTOB_MOSAIC	54	Top to Bottom Mosaic

BBFX_BTOT_MOSAIC	55	Bottom to Top Mosaic

BBFX_LTOR_MOSAIC	56	Left to Right Mosaic

BBFX_RTOL_MOSAIC	57	Right to Left Mosaic

BBFX_EXPLODE_STRETCH	58	Stretch Explode

BBFX_TTOB_STRETCH	59	Stretch Top To Bottom

BBFX_BTOT_STRETCH	60	Stretch Bottom To Top

BBFX_LTOR_STRETCH	61	Stretch Left To Right

BBFX_RTOL_STRETCH	62	Stretch Right To Left

BBFX_CLOSE_STRETCH	63	Stretch while closing horiz.

BBFX_OPEN_STRETCH	64	Stretch while opening horiz.

BBFX_COPEN_STRETCH	65	Stretch vertically

BBFX_CCLOSE_STRETCH	66	Stretch while curtain close

BBFX_PALETTE_FADE	67	Fade into the image using the palette. Works best on 16 color images displayed in 256 color mode.

BBFX_PALETTE_FADE_C20	68	Palette Fade with clear. Use Foreground palette and fade all colors.

BBFX_PALETTE_FADE_C18	69	Palette Fade with clear. Use Foreground palette and fade all colors but Black and White.

BBFX_PALETTE_FADE_C0	70	Palette Fade with clear. Use Foreground palette and fade all but the 20 static colors.

BBFX_PALETTE_FADE_C20NP	71	Palette Fade with clear. Use Background palette and fade all colors.

BBFX_PALETTE_FADE_C18NP	72	Palette Fade with clear. Use Background palette and fade all but Black and White.

BBFX_PALETTE_FADE_C0NP	73	Palette Fade with clear. Use Background palette and fade all but the 20 static colors.

BBFX_TTOB_ROLL_IN	74	Roll image in from top to bottom

BBFX_BTOT_ROLL_IN	75	Roll image in from bottom to top

BBFX_LTOR_ROLL_IN	76	Roll image in from left to right

BBFX_RTOL_ROLL_IN	77	Roll image in from right to left

BBFX_TTOB_ROLL	78	Roll canvas away from top to bottom

BBFX_BTOT_ROLL	79	Roll canvas away from bottom to top

BBFX_LTOR_ROLL	80	Roll canvas away from left to right

BBFX_RTOL_ROLL	81	Roll canvas away from right to left

BBFX_GROW_CIRCLES	82	Growing circles from center

BBFX_GROW_STARS	83	Growing stars from center

BBFX_RAINDROPS	84	Raindrops in a pool of water

BBFX_STARDROPS	85	Growing random stars like raindrops

BBFX_OCTDROPS	86	Growing random octagons like raindrops

BBFX_DIAMONDDROPS	87	Growing random diamonds like raindrops

BBFX_STAR4DROPS	88	Growing random 4 pt stars like raindrops

BBFX_XDROPS	89	Growing random x's like raindrops

BBFX_MOVEAWAY_R	90	Move the canvas right leaving the image

BBFX_MOVEAWAY_RD	91	Move the canvas right/down leaving the image

BBFX_MOVEAWAY_D	92	Move the canvas down leaving the image

BBFX_MOVEAWAY_DL	93	Move the canvas down/left leaving the image

BBFX_MOVEAWAY_L	94	Move the canvas left leaving the image

BBFX_MOVEAWAY_LU	95	Move the canvas left/up leaving the image

BBFX_MOVEAWAY_U	96	Move the canvas up leaving the image

BBFX_MOVEAWAY_UR	97	Move the canvas up/right leaving the image

BBFX_MOVEAWAY_SPIRAL	98	Move the canvas spiral clockwise leaving the image

BBFX_MOVEAWAY_CSPIRAL	99	Move the canvas spiral counter clockwise leaving the image

BBFX_TTOB_LINES	100	Growing lines from top to bottom

BBFX_BTOT_LINES	101	Growing lines from bottom to top

BBFX_LTOR_LINES	102	Growing lines from left to right

BBFX_RTOL_LINES	103	Growing lines from right to left


Distributing the DLL's

There are two license agreements available for Visual FX. The "Application License" allows you to distribute the DLL files along with your program as long as you are not selling your program. The "Reseller License" allows you to distribute the DLL files along with the programs you are selling.


BitBltFX

BOOL FAR PASCAL

BitBltFX(DestDC, x, y, nWidth, nHeight, SrcDC, xSrc, ySrc, Rop,

FX, Grain, SubGrain, Delay, StopKey, UseTransp, TColor, hTable);

HDC DestDC;	/* handle of destination device context	*/

int x;	/* upper-left corner destination rectangle	*/

int y;	/* upper-left corner destination rectangle	*/

int nWidth;	/* bitmap width	*/

int nHeight;	/* bitmap height	*/

HDC SrcDC;	/* handle of source device context	*/

int xSrc;	/* upper-left corner source bitmap	*/

int ySrc;	/* upper-left corner source bitmap	*/

long Rop;	/* raster operation for copy	*/

int FX;	/* special effect to use	*/

int Grain;	/* major effect grain	*/

int SubGrain;	/* minor effect grain	*/

int Delay;	/* effect delay	*/

WPARAM StopKey;	/* key to stop effect	*/

BOOL UseTransp;	/* use transparent color	*/

COLORREF TColor;	/* transparent color	*/

HGLOBAL hTable;	/* handle to movement table	*/

The BitBltFX function copies a bitmap from a specified device context to a destination device context using a special effect and optional movement.

Parameter	Description

DestDC	Identifies the destination device context.

x	Specifies the logical x-coordinate of the upper-left corner of the destination rectangle.

y	Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.

nWidth	Specifies the width, in logical units, of the destination rectangle and source bitmap.

nHeight	Specifies the height, in logical units, of the destination rectangle and source bitmap.

SrcDC	Identifies the device context from which the bitmap will be copied. This parameter must be NULL if the dwRop parameter specifies a raster operation that does not include a source. This parameter can specify a memory device context.

xSrc	Specifies the logical x-coordinate of the upper-left corner of the source bitmap.

ySrc	Specifies the logical y-coordinate of the upper-left corner of the source bitmap.

Rop	Specifies the raster operation to be performed. Raster operation codes define how the graphics device interface (GDI) combines colors in output operations that involve a current brush, a possible source bitmap, and a destination bitmap.

FX	The special effect to use. This can be an integer ranging from 0 to BBFX_MAX_EFFECT. You should use the constants defined in the VISBBFX.H header file that start with BBFX_.

Grain	The grain while doing the effect. You can specify -1 and Visual FX will use a default recommended value.

SubGrain	The secondary grain for effects that require two grains. Some effects (Like the Blocks from top to bottom) use the Grain for the X size and SubGrain for the Y size. Other effects (Like Roll Canvas) use the Grain for the amount moved each location and the SubGrain for the size of the "Roll". You can specify -1 and Visual FX will use a default recommended value.

Delay	The millisecond delay time between each grain. You can specify -1 and Visual FX will use a default recommended value.

StopKey	The key to stop the effect. If you don't want to stop then use BBFX_NOKEY. Use BBFX_ANYKEY for any keyboard input, or BBFX_ANYINPUT for any keyboard or mouse input. If you want a specific key then use the VK_* constants defined in the windows.h file.

UseTransp	Set to true if you want to display the image using the transparent color.

TColor	Transparent color. Use the RGB or PALETTERGB macros to build the transparent color.

hTable	Handle to a global memory object that contains a TABLETYPE0 buffer. This table sets up movement for the image after it is displayed. Movement works best for smaller images. Set this to NULL if you don't want any movement.

Returns

The return is the same as BitBlt. Returns non zero if the function is successful. Otherwise, it is zero. There are extended status codes returned with the BitBltFXStatus function.

Comments

Use the BitBltFX function in places you would normally use the BitBlt function to display bitmaps on the screen. It has the same functionality but with extended parameters for specifying the special effect options.

The speed of the effect is determined by several factors including the speed of the computer, the size of the image, the grains used and the delay factor.

Use the hTable handle to specify movement for the image once the image is displayed. This is a handle to a table that contains an array of coordinates and delays. Refer to the TABLETYPE0 definition for more information.

The sample program VisualFX.exe is a very good place to see the effects in action as well as a good place to see how the functions are implemented.

See Also

BitBltFXStatus, BitBltFXInfo,


BitBltFXStatus

int FAR PASCAL

  BitBltFXStatus(void);

The BitBltFXStatus returns the status of the most recent BitBltFX call.

Returns

The return value is one of the following:

BBFX_OK	Function was successful.

BBFX_ERROR	A windows error occurred.

BBFX_KEYHIT	The user interrupted the effect.

BBFX_OUTOFMEMORY	Failed due to lack of memory.

See Also

BitBltFX, BitBltFXInfo


BitBltFXInfo

void FAR PASCAL

  BitBltFXInfo(int FX, int nWidth, int nHeight, LPFXINFO Info);

int FX;	/* which effect to inquire about	*/

int nWidth;	/* Width of image you are displaying	*/

int nHeight;	/* Height of image you are display	*/

LPFXINFO Info;	/* Pointer to return structure	*/

This function returns in the Info structure the recommended Grain, SubGrain and Delay for the specified effect. It uses the nWidth and nHeight parameters to determine the best values given the size of the image. You can also pass a -1 for the Grain, SubGrain, and Delay parameters to have BitBltFX determine the recommended value.

See the LPFXINFO data type for more information.

Returns

The Info structure contains the Grain, SubGrain, and Delay that is recommended for the specified effect and size.

Parameter	Description

FX	Identifies the effect.

nWidth	Specifies the width of the image you are going to display.

nHeight	Specifies the height of the image you are going to display.

Info	The data structure that returns the recommended Grain, SubGrain & delay.

See Also

BitBltFX


ShowWMFFX

int FAR PASCAL

ShowWMFFX(MfName, DestDC, x, y, nWidth, nHeight,

FX, Grain, SubGrain, Delay, StopKey, UseTransp, TColor, hTable);

LPSTR MFName;	/* pointer to filename string	*/

HDC DestDC;	/* handle of destination device context	*/

int x;	/* upper-left corner destination rectangle	*/

int y;	/* upper-left corner destination rectangle	*/

int nWidth;	/* displayed width	*/

int nHeight;	/* displayed height	*/

int FX;	/* special effect to use	*/

int Grain;	/* major effect grain	*/

int SubGrain;	/* minor effect grain	*/

int Delay;	/* effect delay	*/

WPARAM StopKey;	/* key to stop effect	*/

BOOL UseTransp;	/* use transparent color	*/

COLORREF TColor;	/* transparent color	*/

HGLOBAL hTable;	/* handle to movement table	*/

The ShowWMFFX function reads a WMF file from disk and displays it on a destination device context using a special effect and optional movement.

Parameter	Description

MFName	A pointer to the filename for the WMF file. If the directory is not specified then the current directory is used.

DestDC	Identifies the destination device context.

x	Specifies the logical x-coordinate of the upper-left corner of the destination rectangle.

y	Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.

nWidth	Specifies the width, in logical units, of the destination rectangle.

nHeight	Specifies the height, in logical units, of the destination rectangle.

FX	The special effect to use. This can be an integer ranging from 0 to BBFX_MAX_EFFECT. You should use the constants defined in the VISBBFX.H header file that start with BBFX_.

Grain	The grain while doing the effect. You can specify -1 and Visual FX will use a default recommended value.

SubGrain	The secondary grain for effects that require two grains. Some effects (Like the Blocks from top to bottom) use the Grain for the X size and SubGrain for the Y size. Other effects (Like Roll Canvas) use the Grain for the amount moved each location and the SubGrain for the size of the "Roll". You can specify -1 and Visual FX will use a default recommended value.

Delay	The millisecond delay time between each grain. You can specify -1 and Visual FX will use a default recommended value.

StopKey	The key to stop the effect. If you don't want to stop then use BBFX_NOKEY. Use BBFX_ANYKEY for any keyboard input, or BBFX_ANYINPUT for any keyboard or mouse input. If you want a specific key then use the VK_* constants defined in the windows.h file.

UseTransp	Set to true if you want to display the image using the transparent color.

TColor	Transparent color. Use the RGB or PALETTERGB macros to build the transparent color.

hTable	Handle to a global memory object that contains a TABLETYPE0 buffer. This table sets up movement for the image after it is displayed. Movement works best for smaller images. Set this to NULL if you don't want any movement.

Returns

The return value is zero if successful. Otherwise it is one of the VFX_* error codes.

Comments

The size of the displayed meta file is specified with the nWidth, and nHeight parameters.

See Also

BitBltFX, BitBltFXInfo, ShowDIBFX


ShowDIBFX

int FAR PASCAL

ShowDIBFX(fName, DestDC, PaletteOption, SizeOption, x, y, nWidth, nHeight,

FX, Grain, SubGrain, Delay, StopKey, UseTransp, TColor, hTable);

LPSTR fName;	/* pointer to filename string	*/

HDC DestDC;	/* handle of destination device context	*/

int PaletteOption;	/* how to treat the image palette	*/

int  SizeOption;	/* should image be stretched	*/

int x;	/* upper-left corner destination rectangle	*/

int y;	/* upper-left corner destination rectangle	*/

int nWidth;	/* bitmap width	*/

int nHeight;	/* bitmap height	*/

int FX;	/* special effect to use	*/

int Grain;	/* major effect grain	*/

int SubGrain;	/* minor effect grain	*/

int Delay;	/* effect delay	*/

WPARAM StopKey;	/* key to stop effect	*/

BOOL UseTransp;	/* use transparent color	*/

COLORREF TColor;	/* transparent color	*/

HGLOBAL hTable;	/* handle to movement table	*/

The ShowDIBFX function reads a DIB or BMP file from disk and displays it on a destination device context using a special effect and optional movement.

Parameter	Description

fName	A pointer to the filename for the DIB/BMP file. If the directory is not specified then the current directory is used.

PaletteOption	How should the palette be treated:

PALETTE_NEAR	Match the image palette to what is currently in use.

PALETTE_FILES	Use the palette saved in the image file.

PALETTE_UNIVERSAL	Use a Visual FX universal palette.

SizeOption	Show the image cropping or stretching:

SIZE_FILES	Crop the image to nWidth, nHeight

SIZE_FIT	Stretch/shrink image to nWidth, nHeight

DestDC	Identifies the destination device context.

x	Specifies the logical x-coordinate of the upper-left corner of the destination rectangle.

y	Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.

nWidth	Specifies the width, in logical units, of the destination rectangle.

nHeight	Specifies the height, in logical units, of the destination rectangle.

FX	The special effect to use. This can be an integer ranging from 0 to BBFX_MAX_EFFECT. You should use the constants defined in the VISBBFX.H header file that start with BBFX_.

Grain	The grain while doing the effect. You can specify -1 and Visual FX will use a default recommended value.

SubGrain	The secondary grain for effects that require two grains. Some effects (Like the Blocks from top to bottom) use the Grain for the X size and SubGrain for the Y size. Other effects (Like Roll Canvas) use the Grain for the amount moved each location and the SubGrain for the size of the "Roll". You can specify -1 and Visual FX will use a default recommended value.

Delay	The millisecond delay time between each grain. You can specify -1 and Visual FX will use a default recommended value.

StopKey	The key to stop the effect. If you don't want to stop then use BBFX_NOKEY. Use BBFX_ANYKEY for any keyboard input, or BBFX_ANYINPUT for any keyboard or mouse input. If you want a specific key then use the VK_* constants defined in the windows.h file.

UseTransp	Set to true if you want to display the image using the transparent color.

TColor	Transparent color. Use the RGB or PALETTERGB macros to build the transparent color.

hTable	Handle to a global memory object that contains a TABLETYPE0 buffer. This table sets up movement for the image after it is displayed. Movement works best for smaller images. Set this to NULL if you don't want any movement.

Returns

The return value is zero if successful. Otherwise it is one of the VFX_* error codes.

Comments

See the description for BitBltFX for the effect information.

See Also

BitBltFX, BitBltFXInfo, ShowWMFFX


TABLETYPE0

typedef struct tagTABLETYPE0 {

int	TableType;

HBITMAP	hSaveArea;

int	NumPts;

MOVETYPE	MoveData[1];

} TABLETYPE0;

The TABLETYPE0 structures defines the movement information for Visual FX.

Member	Description

TableType	Defines what type of table. Must be set to TABLE_MOVETYPE.

hSaveArea	Handle to a screen save area. If your program already has a buffer then you can use its buffer within BitBltFX to conserve memory. This can be set to NULL.

NumPts	How many points in the movement array.

MoveData	An array of MOVETYPE specifying the locations and delays for each new location.

See Also

BitBltFX, MOVETYPE


MOVETYPE

typedef struct tagMOVETYPE {

int	Delay;

int	X;

int	Y;

} MOVETYPE;

The MOVETYPE structure defines the Delay, X, and Y values for doing movement.

Member	Description

Delay	The delay in milliseconds between each new location.

X	The x location to display the image.

Y	The y location to display the image.

See Also

BitBltFX, TABLETYPE0


LPFXINFO

typedef struct tagFXINFO {

  int Grain;

  int SubGrain;

  int Delay;

  } FXINFO;

#define LPFXINFO FXINFO far *

The FXINFO structure defines the Grain, SubGrain and Delay for use with the BitBltFXInfo function..

Member	Description

Grain	The suggested Grain size.

SubGrain	The suggested SubGrain size.

Delay	The suggested Delay in milliseconds.

See Also

BitBltFX, BitBltFXInfo


MakeUnivPal256

HPALETTE FAR PASCAL

  MakeUnivPal256(void);

Returns

The return value is the handle to a palette if successful. Otherwise it returns NULL.

Comments

The palette is a fairly good way to display several images on the screen at the same time. If you use this palette for several images in a row, you won't see the palette shift when going from one image to another.

You must use the DeleteObject function to remove the palette from memory when done.